

<!doctype html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>skidl.schlib &#8212; SKiDL 2.2.0 documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
    <link rel="stylesheet" type="text/css" href="../../_static/bizstyle.css?v=a66e137f" />
    
    <script src="../../_static/documentation_options.js?v=b21de401"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../../_static/bizstyle.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <!--[if lt IE 9]>
    <script src="_static/css3-mediaqueries.js"></script>
    <![endif]-->
  </head><body>
    <h1 id="site-title"><a href="../../../../"><img src="../../../../images/slim_banner.png" width="100%"></a></h1>
    
    <div class="related" role="navigation" aria-label="Related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="../../index.html">SKiDL 2.2.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../index.html" accesskey="U">Module code</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">skidl.schlib</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <h1>Source code for skidl.schlib</h1><div class="highlight"><pre>
<span></span><span class="c1"># -*- coding: utf-8 -*-</span>

<span class="c1"># The MIT License (MIT) - Copyright (c) Dave Vandenbout.</span>

<span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Handles schematic libraries for various ECAD tools.</span>

<span class="sd">This module provides classes and functions for loading, managing, and </span>
<span class="sd">accessing schematic component libraries from different ECAD tools.</span>
<span class="sd">&quot;&quot;&quot;</span>

<span class="kn">import</span> <span class="nn">re</span>

<span class="kn">from</span> <span class="nn">.alias</span> <span class="kn">import</span> <span class="n">Alias</span>
<span class="kn">from</span> <span class="nn">.logger</span> <span class="kn">import</span> <span class="n">active_logger</span>
<span class="kn">from</span> <span class="nn">.utilities</span> <span class="kn">import</span> <span class="p">(</span>
    <span class="n">consistent_hash</span><span class="p">,</span>
    <span class="n">cnvt_to_var_name</span><span class="p">,</span>
    <span class="n">export_to_all</span><span class="p">,</span>
    <span class="n">filter_list</span><span class="p">,</span>
    <span class="n">flatten</span><span class="p">,</span>
    <span class="n">is_url</span><span class="p">,</span>
    <span class="n">list_or_scalar</span><span class="p">,</span>
    <span class="n">opened</span><span class="p">,</span>
    <span class="n">get_abs_filename</span><span class="p">,</span>
    <span class="n">norecurse</span><span class="p">,</span>
<span class="p">)</span>


<div class="viewcode-block" id="SchLib">
<a class="viewcode-back" href="../../rst_output/skidl.schlib.html#skidl.schlib.SchLib">[docs]</a>
<span class="nd">@export_to_all</span>
<span class="k">class</span> <span class="nc">SchLib</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    A class for storing parts from a schematic component library file.</span>

<span class="sd">    This class loads and stores electronic components from library files.</span>
<span class="sd">    It provides methods to search, access, and manage the components</span>
<span class="sd">    in the library.</span>

<span class="sd">    Attributes:</span>
<span class="sd">        filename (str): The name of the file from which the parts were read.</span>
<span class="sd">        parts (list): The list of parts (composed of Part objects) in the library.</span>
<span class="sd">        _cache (dict): Class variable that caches libraries for faster loading.</span>

<span class="sd">    Args:</span>
<span class="sd">        filename (str, optional): The name of the library file.</span>
<span class="sd">        tool (str, optional): The format of the library file (e.g., KICAD).</span>
<span class="sd">        lib_section (str, optional): The section of the library to access (for SPICE, only).</span>
<span class="sd">        use_cache (bool, optional): If true, use a cache of libraries to speed up loading.</span>
<span class="sd">        use_pickle (bool, optional): If true, pickle the library for faster loading next time.</span>

<span class="sd">    Keyword Args:</span>
<span class="sd">        attribs: Key/value pairs of attributes to add to the library.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="c1"># Keep a dict of filenames and their associated SchLib object</span>
    <span class="c1"># for fast loading of libraries.</span>
    <span class="n">_cache</span> <span class="o">=</span> <span class="p">{}</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">filename</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
        <span class="n">tool</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
        <span class="n">lib_section</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
        <span class="n">use_cache</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
        <span class="n">use_pickle</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
        <span class="o">**</span><span class="n">attribs</span>
    <span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Load the parts from a library file.</span>
<span class="sd">        </span>
<span class="sd">        Args:</span>
<span class="sd">            filename (str, optional): Path to the library file.</span>
<span class="sd">            tool (str, optional): Tool format (KICAD, SPICE, etc). Defaults to skidl.config.tool.</span>
<span class="sd">            lib_section (str, optional): Section of library for SPICE libs.</span>
<span class="sd">            use_cache (bool, optional): Use cached libraries for speed. Defaults to True.</span>
<span class="sd">            use_pickle (bool, optional): Pickle library for future access. Defaults to True.</span>
<span class="sd">            </span>
<span class="sd">        Keyword Args:</span>
<span class="sd">            attribs: Additional attributes to assign to the library.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="kn">import</span> <span class="nn">os</span>
        <span class="kn">import</span> <span class="nn">pickle</span>
        <span class="kn">import</span> <span class="nn">skidl</span>

        <span class="kn">from</span> <span class="nn">.tools</span> <span class="kn">import</span> <span class="n">tool_modules</span><span class="p">,</span> <span class="n">lib_suffixes</span>

        <span class="n">tool</span> <span class="o">=</span> <span class="n">tool</span> <span class="ow">or</span> <span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">tool</span>

        <span class="c1"># Library starts off empty of parts.</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">parts</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="c1"># Attach attributes to the library.</span>
        <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="nb">list</span><span class="p">(</span><span class="n">attribs</span><span class="o">.</span><span class="n">items</span><span class="p">()):</span>
            <span class="nb">setattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span><span class="p">)</span>

        <span class="c1"># If no filename, just create an empty library and exit.</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">filename</span><span class="p">:</span>
            <span class="k">return</span>

        <span class="c1"># Get the absolute path for the part library file.</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="n">paths</span> <span class="o">=</span> <span class="n">skidl</span><span class="o">.</span><span class="n">lib_search_paths</span><span class="p">[</span><span class="n">tool</span><span class="p">]</span>
            <span class="n">exts</span> <span class="o">=</span> <span class="n">lib_suffixes</span><span class="p">[</span><span class="n">tool</span><span class="p">]</span>
        <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
            <span class="c1"># OK, unknown tool...</span>
            <span class="n">active_logger</span><span class="o">.</span><span class="n">raise_</span><span class="p">(</span>
                <span class="ne">ValueError</span><span class="p">,</span>
                <span class="sa">f</span><span class="s2">&quot;Unsupported ECAD tool library: </span><span class="si">{</span><span class="n">tool</span><span class="si">}</span><span class="s2">.&quot;</span><span class="p">,</span>
            <span class="p">)</span>
        <span class="n">abs_filename</span> <span class="o">=</span> <span class="n">get_abs_filename</span><span class="p">(</span>
            <span class="n">filename</span><span class="p">,</span> <span class="n">paths</span><span class="p">,</span> <span class="n">exts</span><span class="p">,</span> <span class="n">allow_failure</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">descend</span><span class="o">=-</span><span class="mi">1</span>
        <span class="p">)</span>

        <span class="c1"># Don&#39;t pickle files stored in remote repos because it&#39;s difficult to</span>
        <span class="c1"># get their modification times to compare against the local pickled library</span>
        <span class="c1"># to see which is fresher. So remote libs are never pickled.</span>
        <span class="c1"># TODO: Allow pickling of remote part libraries.</span>
        <span class="n">use_pickle</span> <span class="o">=</span> <span class="n">use_pickle</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">is_url</span><span class="p">(</span><span class="n">abs_filename</span><span class="p">)</span>

        <span class="c1"># Get a unique hash to reference the part library file.</span>
        <span class="n">abs_fn_hash</span> <span class="o">=</span> <span class="n">consistent_hash</span><span class="p">(</span><span class="n">abs_filename</span><span class="p">)</span>

        <span class="c1"># Create the absolute file name of the pickle file for storing this part library.</span>
        <span class="c1"># The pickle file name is based on the library name, the tool name, and the hash.</span>
        <span class="c1"># It is stored in a directory specified in the SKIDL configuration file.</span>
        <span class="n">lib_name</span><span class="p">,</span> <span class="n">lib_ext</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">abs_filename</span><span class="p">)[</span><span class="mi">1</span><span class="p">])</span>
        <span class="n">lib_pickle_abs_fn</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
            <span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">pickle_dir</span><span class="p">,</span> <span class="s2">&quot;_&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">((</span><span class="n">lib_name</span><span class="p">,</span> <span class="n">tool</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">abs_fn_hash</span><span class="p">)))</span>
        <span class="p">)</span> <span class="o">+</span> <span class="s2">&quot;.pkl&quot;</span><span class="p">)</span>

        <span class="c1"># Load this SchLib with an existing SchLib object if the file name hash</span>
        <span class="c1"># matches one in the cache.</span>
        <span class="k">if</span> <span class="n">lib_pickle_abs_fn</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="p">[</span><span class="n">lib_pickle_abs_fn</span><span class="p">]</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">)</span>

        <span class="c1"># Load this Schlib from the pickle file if it exists and it&#39;s more recent</span>
        <span class="c1"># than the original part library file.</span>
        <span class="k">elif</span> <span class="p">(</span>
            <span class="n">use_pickle</span>
            <span class="ow">and</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">lib_pickle_abs_fn</span><span class="p">)</span>
            <span class="ow">and</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">getmtime</span><span class="p">(</span><span class="n">lib_pickle_abs_fn</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">getmtime</span><span class="p">(</span><span class="n">abs_filename</span><span class="p">)</span>
        <span class="p">):</span>
            <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">lib_pickle_abs_fn</span><span class="p">,</span> <span class="s2">&quot;rb&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
                <span class="bp">self</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">pickle</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">f</span><span class="p">)</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">)</span>
            <span class="c1"># Cache a reference to the library.</span>
            <span class="k">if</span> <span class="n">use_cache</span><span class="p">:</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="p">[</span><span class="n">lib_pickle_abs_fn</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span>

        <span class="c1"># Otherwise, load from a schematic part library file.</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="c1"># Use the tool name to find the function for loading the library.</span>
            <span class="n">tool_modules</span><span class="p">[</span><span class="n">tool</span><span class="p">]</span><span class="o">.</span><span class="n">load_sch_lib</span><span class="p">(</span>
                <span class="bp">self</span><span class="p">,</span>
                <span class="n">abs_filename</span><span class="p">,</span>
                <span class="c1"># skidl.lib_search_paths[tool],</span>
                <span class="n">lib_section</span><span class="o">=</span><span class="n">lib_section</span><span class="p">,</span>
            <span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">filename</span> <span class="o">=</span> <span class="n">filename</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">filepath</span> <span class="o">=</span> <span class="n">abs_filename</span>
            <span class="c1"># Cache a reference to the library.</span>
            <span class="k">if</span> <span class="n">use_cache</span><span class="p">:</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="p">[</span><span class="n">lib_pickle_abs_fn</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span>
            <span class="c1"># Pickle the library for future use.</span>
            <span class="k">if</span> <span class="n">use_pickle</span><span class="p">:</span>
                <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">pickle_dir</span><span class="p">):</span>
                    <span class="n">os</span><span class="o">.</span><span class="n">mkdir</span><span class="p">(</span><span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">pickle_dir</span><span class="p">)</span>
                <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">lib_pickle_abs_fn</span><span class="p">,</span> <span class="s2">&quot;wb&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
                    <span class="k">try</span><span class="p">:</span>
                        <span class="n">pickle</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span>
                    <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
                        <span class="k">pass</span>
                <span class="c1"># Delete the pickled lib if its size if zero (i.e., a pickling error occurred).</span>
                <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">lib_pickle_abs_fn</span><span class="p">):</span>
                    <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">getsize</span><span class="p">(</span><span class="n">lib_pickle_abs_fn</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
                        <span class="c1"># Delete the file</span>
                        <span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">lib_pickle_abs_fn</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Return a list of the part names in this library as a string.</span>
<span class="sd">        </span>
<span class="sd">        Returns:</span>
<span class="sd">            str: A string listing all parts in the library with their descriptions.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">p</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">p</span><span class="o">.</span><span class="n">description</span><span class="si">}</span><span class="s2">&quot;</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">parts</span><span class="p">])</span>

    <span class="fm">__repr__</span> <span class="o">=</span> <span class="fm">__str__</span>

    <span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Return number of parts in library.</span>
<span class="sd">        </span>
<span class="sd">        Returns:</span>
<span class="sd">            int: The count of parts in the library.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">parts</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get part by name or alias.</span>
<span class="sd">        </span>
<span class="sd">        Args:</span>
<span class="sd">            id: Part name or alias to search for.</span>
<span class="sd">            </span>
<span class="sd">        Returns:</span>
<span class="sd">            Part or list: The matching part(s) or None if not found.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="n">list_or_scalar</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">get_parts_by_name</span><span class="p">(</span><span class="nb">id</span><span class="p">))</span>

    <span class="k">def</span> <span class="fm">__iadd__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">parts</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Add one or more parts to a library using the += operator.</span>
<span class="sd">        </span>
<span class="sd">        Args:</span>
<span class="sd">            *parts: One or more Part objects to add to the library.</span>
<span class="sd">            </span>
<span class="sd">        Returns:</span>
<span class="sd">            SchLib: The library with parts added.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">add_parts</span><span class="p">(</span><span class="o">*</span><span class="n">parts</span><span class="p">)</span>
    
    <span class="k">def</span> <span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Make the library iterable over its parts.</span>
<span class="sd">        </span>
<span class="sd">        Returns:</span>
<span class="sd">            iterator: An iterator over the parts in the library.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">iter</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">parts</span><span class="p">)</span>

<div class="viewcode-block" id="SchLib.reset">
<a class="viewcode-back" href="../../rst_output/skidl.schlib.html#skidl.schlib.SchLib.reset">[docs]</a>
    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">reset</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Clear the cache of processed library files.</span>
<span class="sd">        </span>
<span class="sd">        This clears the class&#39;s internal cache of loaded libraries,</span>
<span class="sd">        which may be useful when reloading libraries or freeing memory.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">cls</span><span class="o">.</span><span class="n">_cache</span> <span class="o">=</span> <span class="p">{}</span></div>


<div class="viewcode-block" id="SchLib.add_parts">
<a class="viewcode-back" href="../../rst_output/skidl.schlib.html#skidl.schlib.SchLib.add_parts">[docs]</a>
    <span class="k">def</span> <span class="nf">add_parts</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">parts</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Add one or more parts to a library.</span>
<span class="sd">        </span>
<span class="sd">        Args:</span>
<span class="sd">            *parts: One or more Part objects to add to the library.</span>
<span class="sd">            </span>
<span class="sd">        Returns:</span>
<span class="sd">            SchLib: The library with parts added.</span>
<span class="sd">            </span>
<span class="sd">        Notes:</span>
<span class="sd">            Parts with the same name are not allowed in the library.</span>
<span class="sd">            A pointer to the library is placed in each added part.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="kn">from</span> <span class="nn">.part</span> <span class="kn">import</span> <span class="n">TEMPLATE</span>

        <span class="k">for</span> <span class="n">part</span> <span class="ow">in</span> <span class="n">flatten</span><span class="p">(</span><span class="n">parts</span><span class="p">):</span>
            <span class="c1"># Parts with the same name are not allowed in the library.</span>
            <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_parts_by_name</span><span class="p">(</span>
                <span class="n">part</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">be_thorough</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">allow_failure</span><span class="o">=</span><span class="kc">True</span>
            <span class="p">):</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">parts</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">part</span><span class="o">.</span><span class="n">copy</span><span class="p">(</span><span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">))</span>
                <span class="c1"># Place a pointer to this library into the added part.</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">parts</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">lib</span> <span class="o">=</span> <span class="bp">self</span>
        <span class="k">return</span> <span class="bp">self</span></div>


<div class="viewcode-block" id="SchLib.get_parts">
<a class="viewcode-back" href="../../rst_output/skidl.schlib.html#skidl.schlib.SchLib.get_parts">[docs]</a>
    <span class="k">def</span> <span class="nf">get_parts</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">use_backup_lib</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="o">**</span><span class="n">criteria</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Return parts from a library that match *all* the given criteria.</span>

<span class="sd">        Args:</span>
<span class="sd">            use_backup_lib (bool, optional): If True and no matches found in this library, </span>
<span class="sd">                search the backup library. Defaults to True.</span>

<span class="sd">        Keyword Args:</span>
<span class="sd">            criteria: One or more keyword-argument pairs. The keyword specifies</span>
<span class="sd">                the attribute name while the argument contains the desired value</span>
<span class="sd">                of the attribute.</span>

<span class="sd">        Returns:</span>
<span class="sd">            list: A list of Parts that match all the criteria.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="kn">import</span> <span class="nn">skidl</span>

        <span class="n">parts</span> <span class="o">=</span> <span class="n">filter_list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">parts</span><span class="p">,</span> <span class="o">**</span><span class="n">criteria</span><span class="p">)</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">parts</span> <span class="ow">and</span> <span class="n">use_backup_lib</span> <span class="ow">and</span> <span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">query_backup_lib</span><span class="p">:</span>
            <span class="k">try</span><span class="p">:</span>
                <span class="n">backup_lib</span> <span class="o">=</span> <span class="n">load_backup_lib</span><span class="p">()</span>
                <span class="n">parts</span> <span class="o">=</span> <span class="n">backup_lib</span><span class="o">.</span><span class="n">get_parts</span><span class="p">(</span><span class="n">use_backup_lib</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="o">**</span><span class="n">criteria</span><span class="p">)</span>
            <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
                <span class="k">pass</span>
        <span class="k">return</span> <span class="n">parts</span></div>


<div class="viewcode-block" id="SchLib.get_parts_quick">
<a class="viewcode-back" href="../../rst_output/skidl.schlib.html#skidl.schlib.SchLib.get_parts_quick">[docs]</a>
    <span class="k">def</span> <span class="nf">get_parts_quick</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Do a quick search for a part name or alias.</span>
<span class="sd">        </span>
<span class="sd">        Args:</span>
<span class="sd">            name (str): Part name or alias to search for.</span>
<span class="sd">            </span>
<span class="sd">        Returns:</span>
<span class="sd">            list: List of parts matching the name or alias.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="p">[</span><span class="n">prt</span> <span class="k">for</span> <span class="n">prt</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">parts</span> <span class="k">if</span> <span class="n">prt</span><span class="o">.</span><span class="n">aliases</span> <span class="o">==</span> <span class="n">name</span><span class="p">]</span></div>


<div class="viewcode-block" id="SchLib.get_parts_by_name">
<a class="viewcode-back" href="../../rst_output/skidl.schlib.html#skidl.schlib.SchLib.get_parts_by_name">[docs]</a>
    <span class="k">def</span> <span class="nf">get_parts_by_name</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">name</span><span class="p">,</span>
        <span class="n">be_thorough</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
        <span class="n">allow_multiples</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
        <span class="n">allow_failure</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
        <span class="n">partial_parse</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
    <span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Return a Part with the given name or alias from the part list.</span>

<span class="sd">        Args:</span>
<span class="sd">            name (str): The part name or alias to search for in the library.</span>
<span class="sd">            be_thorough (bool, optional): Do thorough search, not just simple string matching. Defaults to True.</span>
<span class="sd">            allow_multiples (bool, optional): If true, return a list of parts matching the name.</span>
<span class="sd">                If false, return only the first matching part and issue</span>
<span class="sd">                a warning if there were more than one. Defaults to False.</span>
<span class="sd">            allow_failure (bool, optional): Return None if no matches found. Issue no errors/warnings. Defaults to False.</span>
<span class="sd">            partial_parse (bool, optional): If true, don&#39;t fully parse any parts that are found. Defaults to False.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Part or list: A list of Parts that match the name, or a single Part if only one match,</span>
<span class="sd">                or None if no matches and allow_failure is True.</span>
<span class="sd">                </span>
<span class="sd">        Raises:</span>
<span class="sd">            ValueError: If no parts are found and allow_failure is False.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="c1"># Start with a simple search for the part name.</span>
        <span class="n">names</span> <span class="o">=</span> <span class="n">Alias</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">name</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="n">name</span><span class="o">.</span><span class="n">upper</span><span class="p">())</span>
        <span class="n">parts</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_parts_quick</span><span class="p">(</span><span class="n">names</span><span class="p">)</span>

        <span class="c1"># Simple search failed, so try the more thorough search method.</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">parts</span> <span class="ow">and</span> <span class="n">be_thorough</span><span class="p">:</span>
            <span class="n">parts</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_parts</span><span class="p">(</span><span class="n">aliases</span><span class="o">=</span><span class="n">name</span><span class="p">)</span>

        <span class="c1"># No parts found, so signal an error.</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">parts</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">allow_failure</span><span class="p">:</span>
            <span class="n">message</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;Unable to find part </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2"> in library </span><span class="si">{</span><span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;filename&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;UNKNOWN&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2">.&quot;</span>
            <span class="n">active_logger</span><span class="o">.</span><span class="n">raise_</span><span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="n">message</span><span class="p">)</span>

        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">parts</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">allow_multiples</span><span class="p">:</span>
            <span class="n">message</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;Found multiple parts matching </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">. Selecting </span><span class="si">{</span><span class="n">parts</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">.&quot;</span>
            <span class="n">active_logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
            <span class="n">parts</span> <span class="o">=</span> <span class="n">parts</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">1</span><span class="p">]</span>  <span class="c1"># Just keep the first part.</span>

        <span class="c1"># Do whatever parsing was requested for the found parts.</span>
        <span class="k">for</span> <span class="n">part</span> <span class="ow">in</span> <span class="n">parts</span><span class="p">:</span>
            <span class="n">part</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">partial_parse</span><span class="p">)</span>

        <span class="k">return</span> <span class="n">parts</span></div>


<div class="viewcode-block" id="SchLib.export">
<a class="viewcode-back" href="../../rst_output/skidl.schlib.html#skidl.schlib.SchLib.export">[docs]</a>
    <span class="k">def</span> <span class="nf">export</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">libname</span><span class="p">,</span> <span class="n">file_</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">tool</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">addtl_part_attrs</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Export a library into a file.</span>

<span class="sd">        Args:</span>
<span class="sd">            libname (str): A string containing the name of the library.</span>
<span class="sd">            file_ (str or file object, optional): The file the library will be exported to. </span>
<span class="sd">                It can either be a file object or a string or None. If None, the file</span>
<span class="sd">                will be the same as the library name with the library suffix appended.</span>
<span class="sd">            tool (str, optional): The CAD tool library format to be used. Currently, this can</span>
<span class="sd">                only be SKIDL.</span>
<span class="sd">            addtl_part_attrs (list, optional): List of additional part attribute names to include in export.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">def</span> <span class="nf">prettify</span><span class="p">(</span><span class="n">s</span><span class="p">):</span>
<span class="w">            </span><span class="sd">&quot;&quot;&quot;Breakup and indent library export string.&quot;&quot;&quot;</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="sa">r</span><span class="s2">&quot;(Part\()&quot;</span><span class="p">,</span> <span class="sa">r</span><span class="s2">&quot;\n        \1&quot;</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="sa">r</span><span class="s2">&quot;(Pin\()&quot;</span><span class="p">,</span> <span class="sa">r</span><span class="s2">&quot;\n            \1&quot;</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">s</span>

        <span class="kn">from</span> <span class="nn">skidl</span> <span class="kn">import</span> <span class="n">SKIDL</span>
        <span class="kn">from</span> <span class="nn">skidl.tools</span> <span class="kn">import</span> <span class="n">lib_suffixes</span>

        <span class="k">if</span> <span class="n">tool</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">tool</span> <span class="o">=</span> <span class="n">SKIDL</span>

        <span class="n">file_</span> <span class="o">=</span> <span class="n">file_</span> <span class="ow">or</span> <span class="p">(</span><span class="n">libname</span> <span class="o">+</span> <span class="n">lib_suffixes</span><span class="p">[</span><span class="n">tool</span><span class="p">])</span>

        <span class="n">export_str</span> <span class="o">=</span> <span class="s2">&quot;from collections import defaultdict</span><span class="se">\n</span><span class="s2">&quot;</span>
        <span class="n">export_str</span> <span class="o">+=</span> <span class="s2">&quot;from skidl import Pin, Part, Alias, SchLib, SKIDL, TEMPLATE</span><span class="se">\n\n</span><span class="s2">&quot;</span>
        <span class="n">export_str</span> <span class="o">+=</span> <span class="s2">&quot;from skidl.pin import pin_types</span><span class="se">\n\n</span><span class="s2">&quot;</span>
        <span class="n">export_str</span> <span class="o">+=</span> <span class="s2">&quot;SKIDL_lib_version = &#39;0.0.1&#39;</span><span class="se">\n\n</span><span class="s2">&quot;</span>
        <span class="n">part_export_str</span> <span class="o">=</span> <span class="s2">&quot;,&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
            <span class="p">[</span><span class="n">p</span><span class="o">.</span><span class="n">export</span><span class="p">(</span><span class="n">addtl_part_attrs</span><span class="o">=</span><span class="n">addtl_part_attrs</span><span class="p">)</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">parts</span><span class="p">]</span>
        <span class="p">)</span>
        <span class="n">export_str</span> <span class="o">+=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">cnvt_to_var_name</span><span class="p">(</span><span class="n">libname</span><span class="p">)</span><span class="si">}</span><span class="s2"> = SchLib(tool=SKIDL).add_parts(*[</span><span class="si">{</span><span class="n">part_export_str</span><span class="si">}</span><span class="s2">])&quot;</span>
        <span class="n">export_str</span> <span class="o">=</span> <span class="n">prettify</span><span class="p">(</span><span class="n">export_str</span><span class="p">)</span>
        <span class="k">with</span> <span class="n">opened</span><span class="p">(</span><span class="n">file_</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
            <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">export_str</span><span class="p">)</span></div>
</div>



<span class="nd">@export_to_all</span>
<span class="nd">@norecurse</span>
<span class="k">def</span> <span class="nf">load_backup_lib</span><span class="p">():</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Load a backup library that stores the parts used in the circuit.</span>
<span class="sd">    </span>
<span class="sd">    Returns:</span>
<span class="sd">        SchLib: The backup library containing previously used parts, or None if not available.</span>
<span class="sd">        </span>
<span class="sd">    Notes:</span>
<span class="sd">        This function attempts to load a backup library stored as a Python module.</span>
<span class="sd">        The backup library is only loaded once; subsequent calls return the cached library.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">skidl</span>

    <span class="c1"># Don&#39;t keep reloading the backup library once it&#39;s loaded.</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">backup_lib</span><span class="p">:</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="c1"># The backup library is a SKiDL lib stored as a Python module.</span>
            <span class="n">glb_vars</span><span class="p">,</span> <span class="n">loc_vars</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span> <span class="nb">locals</span><span class="p">()</span>
            <span class="n">exec</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">backup_lib_file_name</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">(),</span> <span class="n">glb_vars</span><span class="p">,</span> <span class="n">loc_vars</span><span class="p">)</span>
            <span class="c1"># Copy the backup library in the local storage to the global storage.</span>
            <span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">backup_lib</span> <span class="o">=</span> <span class="n">loc_vars</span><span class="p">[</span><span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">backup_lib_name</span><span class="p">]</span>

        <span class="k">except</span> <span class="p">(</span><span class="ne">FileNotFoundError</span><span class="p">,</span> <span class="ne">ImportError</span><span class="p">,</span> <span class="ne">NameError</span><span class="p">,</span> <span class="ne">IOError</span><span class="p">):</span>
            <span class="k">pass</span>

    <span class="k">return</span> <span class="n">skidl</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">backup_lib</span>
</pre></div>

            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
<search id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="Related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="../../index.html">SKiDL 2.2.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../index.html" >Module code</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">skidl.schlib</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
    &#169; Copyright 2016-2025, Dave Vandenbout.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
    </div>
  </body>
</html>